Description

This PR introduces support for SystemContentBlock arrays in the Agent constructor, enabling provider-agnostic caching and multi-prompt system configurations.

Design Choices

Users can now pass SystemContentBlock arrays directly to the Agent constructor via the system_prompt parameter, which supports rich content including cache points, multiple text blocks, and future extensibility for other content types.

The system_prompt_content parameter becomes the authoritative source that flows through the entire pipeline from Agent initialization to model providers. When both system_prompt and system_prompt_content are provided, system_prompt_content takes precedence. The existing system_prompt parameter is maintained for backwards compatibility.

Implementation Strategy

The refactoring touches three key areas: Agent initialization logic that processes SystemContentBlock arrays, the streaming event loop that now accepts both parameters with clear precedence rules, and model provider implementations that handle the structured content appropriately.

For Bedrock specifically, the implementation leverages native SystemContentBlock support while deprecating the legacy cache_prompt configuration in favor of explicit cachePoint blocks within the system content. Other providers receive a concatenated string representation for compatibility.

Backwards Compatibility

All existing Agent constructor calls continue to work unchanged. The system_prompt parameter still functions as before, and existing Bedrock cache_prompt configurations are supported with deprecation warnings. The streaming interface maintains the same public API while internally handling both parameter types.

Provider Agnostic Benefits

This approach enables caching across all model providers through a unified interface rather than requiring provider-specific arguments. Users can define cache points, multi-prompt systems, and other advanced system configurations using the same SystemContentBlock format regardless of their chosen model provider.

The follow-up work will implement LiteLLM mappings to extend this provider-agnostic approach to additional model providers, making advanced system prompt features available across the entire ecosystem through this standardized interface.

Related Issues

#937

Documentation PR

ToDo

Type of Change

New feature

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.